Summary

Closes #2446 with a first version of shared Workflow configuration:

• adds a Zod-validated workflow.config.ts, typed through workflow/config
• keeps the config static and identifies a World provider by module specifier
• generates a runtime-only binding that bundlers can statically discover
• shares build, queue, and integration settings across the CLI, Next.js, Nitro, and NestJS
• preserves existing environment variables and framework options with explicit precedence

Application config

// workflow.config.ts
import type { WorkflowConfig } from 'workflow/config';

const config = {
  world: './workflow.world.ts',
  build: {
    dirs: ['workflows'],
    sourcemap: false,
    manifest: { public: true },
  },
  queue: {
    namespace: 'myapp',
  },
  integration: {
    type: 'next',
    local: { port: 4000 },
  },
} satisfies WorkflowConfig;

export default config;

world can be a path relative to workflow.config.ts or a package specifier. Next.js projects still use withWorkflow(nextConfig) to activate the integration.

World provider

The referenced module default-exports a WorldProvider:

// workflow.world.ts
import type { WorldProvider } from 'workflow/config';
import { createWorld } from '@workflow/world-postgres';

const world: WorldProvider = () =>
  createWorld({
    connectionString: process.env.WORKFLOW_POSTGRES_URL!,
    jobPrefix: 'myapp_',
    queueConcurrency: 50,
    maxPoolSize: 52,
  });

export default world;

The config loader validates the module location but does not import or call the provider. Framework bundlers alias a generated runtime binding containing a literal lazy import, so the provider has a statically discoverable source file while its infrastructure is created only when the runtime first needs the World.

There are no provider IDs, package-name fields, wrapper helpers, or function serialization.

Worlds by environment

Runtime selection belongs in the provider module:

import type { WorldProvider } from 'workflow/config';
import { createLocalWorld } from '@workflow/world-local';
import { createWorld as createPostgresWorld } from '@workflow/world-postgres';

const world: WorldProvider = () => {
  switch (process.env.NODE_ENV) {
    case 'production':
      return createPostgresWorld({
        connectionString: process.env.WORKFLOW_POSTGRES_URL!,
      });
    case 'development':
    case 'test':
      return createLocalWorld();
    default:
      throw new Error(`Unexpected NODE_ENV: ${process.env.NODE_ENV}`);
  }
};

export default world;

World package contract

World packages can keep exposing a typed createWorld(options) API. An application can adapt it in workflow.world.ts, as above. A package that is directly usable as the config's world value may also default-export a zero-argument provider:

import type { WorldProvider } from '@workflow/world';

export function createWorld(options: WorldOptions): World {
  // ...
}

export default (() => createWorld(readRuntimeOptions())) satisfies WorldProvider;

Config behavior

Precedence is, from highest to lowest:

explicit CLI/framework options > environment variables > workflow.config.ts > defaults

WORKFLOW_TARGET_WORLD therefore continues to override the configured provider. Existing environment variables remain supported without warnings or build failures.

The config default export must be a plain object. Its type is inferred from the Zod schema, and integration is a discriminated union so Next.js, Nitro, and NestJS settings cannot be mixed.

Remaining questions

• Runtime secrets should live in workflow.world.ts, not workflow.config.ts. The static config is still executable TypeScript at build time, so module-scope side effects remain possible.
• withWorkflow, Nitro, and Nest options remain activation points and explicit overrides. This PR does not deprecate their overlapping options.
• Nest currently discovers the config during onModuleInit because it does not have a separate build-plugin boundary. Next.js, Nitro, and the standalone build path generate their runtime binding during build/dev setup.
• A later migration can decide whether any legacy environment variables should warn or be removed. This version keeps backward compatibility.

Verification

• rebased onto main, including Next.js root-entrypoint discovery
• affected package TypeScript builds passed
• 1,681 package tests passed across builders, config, core, CLI, Nest, Next, Nitro, workflow, and world
• 1,016 documentation samples passed; 329 explicitly skipped samples remained skipped
• baseline and configured Next.js Turbopack production builds passed
• configured build emitted the namespaced __configured_wkf_workflow_* queue trigger
• all 10 PR commits contain SSH signatures and Nathan's DCO signoff

Docs Preview